Conversation
- Introduced comprehensive authoring guides for TSDoc and JSDoc, including best practices for writing documentation comments. - Created detailed reference documents outlining TSDoc comment structure, tag kinds, and high-quality patterns. - Established focused indexes for TSDoc and JSDoc rules to streamline documentation processes. - Added specific rules for documenting async behavior, constructors, and object shapes to enhance clarity and consistency in API documentation. - Implemented checks for required tags and descriptions to ensure thorough documentation standards across JavaScript and TypeScript projects.
- Adjusted indentation in various documentation files to ensure consistent formatting. - Updated examples in the TSDoc and JSDoc rules to enhance readability and maintainability.
- Introduced new documentation files: CLI Reference, Configuration, Quickstart, and Workspace Guide. - Detailed command usage, options, and configuration fields for `readie.json` and `readie.global.json`. - Enhanced the main documentation index to improve navigation and accessibility for users.
|
No actionable comments were generated in the recent review. 🎉 📜 Recent review detailsConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds a comprehensive TSDoc/JSDoc authoring skill (many rule/index/reference Markdown files), new Readie docs, CLI invocation typing and help, global config discovery/merging with placeholder interpolation, README template/TOC generation, and workspace README orchestration and CLI commands/types. Changes
Sequence DiagramsequenceDiagram
participant CLI as User/CLI
participant Invocation as InvocationResolver
participant ConfigLoader as ConfigLoader
participant Generator as READMEGenerator
participant FS as FileSystem
CLI->>Invocation: resolveInvocation(args)
Invocation->>Invocation: modeFromToken()
Invocation-->>CLI: ResolvedInvocation
alt mode == "generate:workspace"
Invocation->>ConfigLoader: loadGlobalConfig(startDir)
ConfigLoader->>FS: search upward for readie.global.json
FS-->>ConfigLoader: global config / null
Invocation->>Generator: generateWorkspaceReadmes(root, configName, packageFilter, dryRun)
Generator->>FS: listProjectDirsWithConfig(root)
FS-->>Generator: [projectDirs...]
loop for each projectDir
Generator->>ConfigLoader: loadReadieConfig(projectConfigPath)
ConfigLoader->>ConfigLoader: mergeConfigs(globalConfig, projectConfig)
ConfigLoader->>ConfigLoader: interpolatePlaceholders(mergedConfig)
ConfigLoader-->>Generator: merged ReadieConfig
Generator->>FS: readExistingContent(README.md)
Generator->>Generator: baseReadmeTemplate(mergedConfig)
Generator->>FS: write README.md (unless dryRun)
FS-->>Generator: success / error
Generator->>Generator: recordResult(updated/unchanged/failed)
end
Generator-->>CLI: GenerateWorkspaceResult
end
Estimated code review effort🎯 5 (Critical) | ⏱️ ~120 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (2 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 23
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (69)
.agents/skills/tsdoc-jsdoc-authoring/AGENTS.md.agents/skills/tsdoc-jsdoc-authoring/SKILL.md.agents/skills/tsdoc-jsdoc-authoring/indexes/jsdoc-authoring-index.md.agents/skills/tsdoc-jsdoc-authoring/indexes/jsdoc-consistency-index.md.agents/skills/tsdoc-jsdoc-authoring/indexes/tsdoc-index.md.agents/skills/tsdoc-jsdoc-authoring/reference.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-async.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-class-constructor.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-implements-on-classes.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-module.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-typedef-property.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-yields.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-check-access.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-example.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-no-defaults.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-optional-default.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-param.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-property-namepaths.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param-type.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-description.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-name.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-type.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns-description.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns-type.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-yields.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-returns.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-summary.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-throws.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-deprecated.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-example.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-param.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-remarks.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-returns.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-summary.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-throws.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-typeparam.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-inheritdoc.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-label.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-link.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-see.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-default-value.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-modifier-tags.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-no-jsdoc-braces.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-package-documentation.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-private-remarks.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-release-tags.md.claude/skills/tsdoc-jsdoc-authoring.cursor/skills/tsdoc-jsdoc-authoringdocs/cli-reference.mdxdocs/configuration.mdxdocs/index.mdxdocs/introduction.mdxdocs/meta.jsondocs/quickstart.mdxdocs/workspace.mdxsrc/cli/commands/generate-workspace.tssrc/cli/commands/generate.tssrc/cli/commands/init.tssrc/cli/help.tssrc/cli/resolve-invocation.tssrc/config/load-config.tssrc/config/starter-config.tssrc/config/types.tssrc/index.tssrc/readme-generator/generator.tssrc/readme-generator/template.ts
🧰 Additional context used
🪛 LanguageTool
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-example.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...vious, or high-value usage patterns. Use this when: behavior is subtle or edge...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-module.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...age organization and generated docs. Use this when: documenting JavaScript mod...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-private-remarks.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...at should not appear in public docs. Use this when: maintainers need migration...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-throws.md
[grammar] ~15-~15: Use a hyphen to join words.
Context: ...with no contract value. Incorrect (no throws contract): ```js /** * Parses...
(QB_NEW_EN_HYPHEN)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-param.md
[grammar] ~57-~57: Use a hyphen to join words.
Context: ... Preferred (VS Code hover/autocomplete friendly pattern): ```ts type SearchO...
(QB_NEW_EN_HYPHEN)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-deprecated.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... with explicit replacement guidance. Use this when: a symbol should no longer ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-remarks.md
[style] ~10-~10: Consider a different adjective to strengthen your wording.
Context: ...r Long-Form Context Use @remarks for deeper context, caveats, and non-trivial behav...
(DEEP_PROFOUND)
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ..., caveats, and non-trivial behavior. Use this when: summary alone cannot expre...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-see.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ts, alternatives, or companion APIs. Use this when: relationship is important ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-inheritdoc.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...alent to the referenced declaration. Use this when: override/wrapper keeps the...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/index.mdx
[grammar] ~8-~8: Ensure spelling is correct
Context: ...tModified: 2026-02-19 full: true --- # Readie Documentation Readie is a developer-fi...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-label.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...vanced reference labeling scenarios. Use this when: your doc tooling relies on...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/reference.md
[uncategorized] ~194-~194: The official name of this software platform is spelled with a capital “H”.
Context: ... /microsoft/tsdoc (Context7) - JSDoc: /jsdoc/jsdoc.github.io (Context7)
(GITHUB)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-package-documentation.md
[style] ~12-~12: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ntrypoint docs, not regular members. Use this when: documenting package/module...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/introduction.mdx
[style] ~24-~24: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...kdown from your configured sections. 4. Readie writes README.md (or a custom output ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-throws.md
[grammar] ~15-~15: Use a hyphen to join words.
Context: ... no API contract value. Incorrect (no throw contract): ```ts /** * Parses ...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (65)
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-async.md (1)
1-34: Clear and actionable guidance for@async.Examples and “use/avoid” criteria are concise and well-structured.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-implements-on-classes.md (1)
1-43: Clear, consistent rule and examples.
The guidance and examples align with the stated restriction and are easy to follow..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-class-constructor.md (1)
1-34: LGTM — clear guidance and examples.The metadata and examples are concise and align with the goal of clarifying constructor contracts.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-typedef-property.md (1)
15-37: LGTM! Clear and correct examples.The code examples effectively demonstrate the difference between inline object shapes and reusable typedefs. The JSDoc syntax in both examples is correct, and the contrast clearly illustrates the benefit of using
@typedefand@propertyfor shared object structures..claude/skills/tsdoc-jsdoc-authoring (1)
1-1: This file is a symbolic link, not a text file with a path reference.The review comment is based on an incorrect understanding of the file structure. The output from
ls -lashows that.claude/skills/tsdoc-jsdoc-authoringis a symbolic link (lrwxrwxrwx) pointing to../../.agents/skills/tsdoc-jsdoc-authoring, not a text file containing that path as content. The.cursor/skills/directory uses the identical structure. This is the correct implementation—a single source of truth (the skill directory in.agents/skills/) with symlinks from AI-specific tool directories. The trailing newline concern does not apply to symbolic links.Likely an incorrect or invalid review comment.
.cursor/skills/tsdoc-jsdoc-authoring (1)
1-1: The target directory.agents/skills/tsdoc-jsdoc-authoringexists and contains the expected documentation, including AGENTS.md, SKILL.md, reference.md, and comprehensive indexes and rule files. The file reference is correct.src/config/types.ts (1)
1-169: LGTM!The type definitions are well-structured with comprehensive TSDoc comments. The extraction of
GenerateWorkspaceFailureinto a named interface improves clarity and reusability. Usingunknownfor the error type is the correct TypeScript practice for capturing arbitrary error values..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-modifier-tags.md (1)
1-35: LGTM!The examples effectively illustrate the principle of semantic correctness for modifier tags. The contrast between
let(mutable) with@readonlyvsconst(immutable) with@readonlyclearly demonstrates when tags should match actual behavior..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-link.md (1)
1-31: LGTM!Clear guidance with effective examples demonstrating the benefit of navigable
{@link...}references over plain text symbol names..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-see.md (1)
1-33: LGTM!The guidance for
@seetags is clear with good examples showing how to connect related APIs. The "Use this when/Avoid this when" pattern is consistent with other rule docs in this set..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns-type.md (1)
1-29: LGTM! Clear and well-structured documentation.The rule is clearly articulated with appropriate examples demonstrating both incorrect and correct usage patterns. The impact level (HIGH) is appropriate for type safety requirements.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-default-value.md (1)
1-32: LGTM! Appropriate guidance for API documentation.The
@defaultValuetag usage is correctly demonstrated. While the default value is visible in the code (= 3), the tag ensures it's explicitly documented in generated API documentation, which is standard practice for tools like TypeDoc..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-private-remarks.md (1)
1-34: LGTM! Effective guidance on separating public and internal documentation.The examples clearly demonstrate when to use
@privateRemarksversus public@remarks, which is valuable for maintaining clean public API documentation.Note: The static analysis tool flagged repetitive sentence structure ("Use this when..." / "Avoid this when..."), but this is clearly an intentional template pattern used consistently across all these documentation files for scannability.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-name.md (1)
1-33: LGTM! Clear requirement for property identifiability.The rule appropriately mandates property names in
@propertytags, with clear examples demonstrating the requirement in typedef contexts..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-release-tags.md (1)
1-36: LGTM! Critical guidance for API lifecycle management.The policy correctly emphasizes consistency in release tagging and provides a clear example of a common mistake (conflicting
@public/@internal tags). The CRITICAL impact level is appropriate given the importance of clear API stability communication..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-no-jsdoc-braces.md (1)
1-33: LGTM! Essential guidance for TypeScript documentation consistency.The distinction between JSDoc and TSDoc syntax is clearly articulated, with practical examples showing the correct approach for TypeScript codebases. The CRITICAL impact is justified given potential parser/tooling incompatibilities.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-type.md (1)
1-33: LGTM! Clear type requirement for property documentation.The rule appropriately mandates explicit type expressions in
@propertytags, with well-chosen examples demonstrating the requirement in typedef contexts..agents/skills/tsdoc-jsdoc-authoring/indexes/jsdoc-consistency-index.md (1)
1-37: LGTM! Well-organized index for JSDoc consistency rules.The index provides clear categorization of rules into logical sections (Access/Class Semantics, Parameter Requirements, Property Requirements, etc.), making it easy to navigate the documentation set. All referenced rule files exist and the reference.md file is in place.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property.md (1)
1-45: LGTM! Clear and well-structured documentation.The rule documentation is well-written with clear examples demonstrating both incorrect and correct usage. The intentional use of both
{Object}(line 21) and{object}(line 42) correctly reflects JSDoc's support for both forms..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns-description.md (1)
1-36: LGTM! Clear exception handling and examples.The documentation clearly explains when to require return descriptions and appropriately lists exceptions for void/undefined return types.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-optional-default.md (1)
1-34: LGTM! Clear syntax guidance with appropriate impact level.The documentation effectively demonstrates the correct optional/default parameter syntax with clear examples. The CRITICAL impact designation is appropriate given the potential for runtime errors from optionality confusion.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-returns.md (1)
1-31: LGTM! Strong emphasis on semantic contracts.The documentation effectively promotes documenting return semantics and guarantees rather than merely restating types. The example of a "deterministic cache key" is particularly instructive.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-returns.md (1)
1-31: LGTM! JSDoc-specific guidance with inline type notation.The documentation appropriately demonstrates JSDoc's inline type notation for object shapes and emphasizes semantic descriptions over bare type declarations.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-summary.md (1)
1-31: LGTM! Clear guidance on writing meaningful summaries.The documentation effectively contrasts superficial name restatements with meaningful behavioral descriptions. The examples clearly demonstrate best practices.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-summary.md (1)
1-31: LGTM! Behavior-focused summary guidance.The documentation clearly demonstrates the value of behavior-focused summaries over name restatements, with effective before/after examples.
.agents/skills/tsdoc-jsdoc-authoring/indexes/jsdoc-authoring-index.md (1)
1-30: All referenced documentation files exist and are properly linked. No action required.Likely an incorrect or invalid review comment.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-remarks.md (1)
1-36: LGTM!The documentation clearly explains when to use
@remarksfor extended context and provides accurate examples distinguishing overloaded summaries from properly structured TSDoc blocks..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-label.md (1)
1-33: LGTM!The guidance correctly positions
{@Label...}as an advanced feature and appropriately recommends{@link...}for standard cross-reference scenarios. Examples clearly illustrate the distinction.src/cli/commands/init.ts (1)
8-20: LGTM!The JSDoc additions provide clear documentation for the interface and command. The descriptions are concise and accurately reflect the behavior of each property and the command's purpose.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-typeparam.md (1)
1-32: LGTM!The guidance correctly emphasizes documenting generic type parameters with
@typeParamand provides clear before/after examples that effectively illustrate proper generic documentation..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/policy/tsdoc-package-documentation.md (1)
1-32: LGTM!The guidance correctly explains that
@packageDocumentationbelongs at the module/entrypoint level, not on individual functions. The examples effectively demonstrate the distinction..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns.md (1)
17-53: LGTM!The examples comprehensively cover both missing and duplicate
@returnsanti-patterns, and the configuration options are clearly documented with appropriate defaults..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-deprecated.md (1)
1-31: LGTM!The documentation is clear, well-structured, and provides actionable guidance with concrete incorrect/correct examples. The parallel "Use this when" / "Avoid this when" phrasing is intentional for documentation consistency across rule files, so the static analysis style suggestion can be ignored.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-check-access.md (1)
1-53: LGTM!Clear documentation with comprehensive examples covering mixed access styles, invalid values, and both explicit and shorthand correct patterns.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-param.md (1)
59-71: LGTM!The preferred pattern demonstrating named types with property-level documentation is excellent guidance for VS Code IntelliSense optimization.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/crossref/tsdoc-inheritdoc.md (1)
1-39: LGTM!Excellent guidance on a common documentation pitfall. The examples clearly illustrate why blindly inheriting docs can mislead consumers when wrapper behavior differs from the base.
.agents/skills/tsdoc-jsdoc-authoring/AGENTS.md (1)
1-228: LGTM!Well-structured reference catalog with clear navigation via the rule index, appropriate load-order guidance, and comprehensive coverage of TSDoc and JSDoc patterns across core contracts, cross-references, internal notes, stability policy, and JavaScript-specific rules.
docs/configuration.mdx (1)
1-57: LGTM!Clear and comprehensive configuration reference covering field definitions, merge semantics, and placeholder interpolation with practical examples.
src/config/starter-config.ts (1)
1-27: LGTM!Clean implementation with appropriate JSDoc documentation. The
starterConfigTextexport provides a convenient ready-to-write format for file output, and the config fields align with the documented schema.src/cli/resolve-invocation.ts (1)
1-64: LGTM!Well-structured CLI argument resolution with clear type definitions and appropriate edge case handling. The distinction between preserving full
argsfor "unknown" mode (useful for error messages) versus passingrestfor known commands is correct.src/cli/help.ts (1)
1-26: LGTM!The help function is well-documented and provides clear, comprehensive CLI usage information covering all available commands and examples.
src/cli/commands/generate.ts (1)
6-78: LGTM!The interface is well-typed with clear JSDoc documentation, the
resultStatushelper correctly handles all three states (no changes, dry-run, actual generation), and the command implementation properly integrates with Effect's error handling patterns.src/config/load-config.ts (4)
7-125: LGTM!The schema definitions are comprehensive and the JSON parsing includes proper error handling with cause chaining for debugging.
175-198: LGTM!The upward directory traversal correctly terminates at the filesystem root (when
parent === current) and properly handles the case when no global config exists by returningnull.
207-278: LGTM!The interpolation logic is well-structured with clear separation between placeholder creation, string interpolation, and custom section handling. The regex pattern correctly captures placeholder tokens with optional whitespace.
354-425: LGTM!The merging logic correctly implements project-over-global precedence with explicit
nullhandling to clear inherited values. The post-merge interpolation ensures placeholders are resolved after all values are combined.src/readme-generator/template.ts (3)
126-165: LGTM!The
ReadmeSectionsinterface is well-documented with JSDoc comments for each field, providing clear guidance on what each block represents.
224-289: LGTM!The TOC generation correctly handles duplicate headings by suffixing with incremental numbers, and respects the opt-out pattern where
includeTableOfContents: falseexplicitly disables the TOC while undefined or truthy values enable it.
291-331: LGTM!The
baseReadmeTemplatefunction correctly assembles all sections, normalizes excessive blank lines, and ensures a single trailing newline for consistent output formatting.docs/meta.json (1)
1-10: LGTM!The documentation page index is well-structured with a logical ordering that guides users from introduction through to advanced CLI reference.
docs/index.mdx (1)
1-26: LGTM!The documentation landing page provides a clear overview of Readie's capabilities and logical navigation paths for different user needs.
.agents/skills/tsdoc-jsdoc-authoring/indexes/tsdoc-index.md (1)
1-39: LGTM!The TSDoc index is well-organized with logical categorization of rules (Core Contract, Cross-Reference, Package/Policy) that enables selective loading of relevant documentation.
docs/cli-reference.mdx (1)
1-58: LGTM!The CLI reference is comprehensive and accurately documents all commands and options with their defaults, aligning with the implementation in the source files.
docs/quickstart.mdx (1)
1-56: Clear, actionable quickstart.The stepwise flow and sample config make onboarding straightforward.
.agents/skills/tsdoc-jsdoc-authoring/SKILL.md (1)
1-123: Well-structured skill definition.The routing guidance and rule structure are clear and actionable.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-example.md (1)
1-34: Concise and clear example guidance.The incorrect/correct contrast is easy to follow.
src/cli/commands/generate-workspace.ts (1)
10-105: Solid CLI wiring and summary output.The command definition, argument parsing, and summary reporting look consistent.
src/index.ts (1)
33-87: Clean orchestration and error handling flow.Mode resolution and error normalization are straightforward and robust.
.agents/skills/tsdoc-jsdoc-authoring/reference.md (2)
1-17: Well-structured TSDoc reference document.The comment structure guidance and ordering (summary → remarks → params → returns → throws → example → policy tags → see) follows established TSDoc conventions and provides clear, actionable guidance for AI agents.
59-98: High-quality code examples demonstrating TSDoc patterns.The examples correctly show async documentation, generic type parameters, and error contracts with proper tag usage and formatting.
src/readme-generator/generator.ts (5)
24-35: LGTM onparsePackageListimplementation.The logic correctly handles comma-separated values, trims whitespace, filters empty strings, and deduplicates via Set.
60-73: LGTM onresolvePackageNameimplementation.Appropriately handles missing
package.jsonand validates thatnameis a non-empty string before returning.
105-137: LGTM ongenerateReadmeFromConfigimplementation.Change detection via string comparison is efficient, and the dry-run flag correctly skips the write operation while still returning
updated: true.
142-159: LGTM onlistProjectDirsWithConfig.Good use of
Promise.allfor parallel config existence checks across directories.
236-273: LGTM ongenerateWorkspaceReadmesorchestration.The sequential processing via
for...ofensures predictable logging order and avoids potential race conditions when mutating the sharedresultobject. The error handling correctly isolates failures per project without aborting the entire batch.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/tsdoc-jsdoc-authoring/reference.md:
- Around line 191-194: The "(Context7)" tag in the "## 9) Sources Used For This
Skill" section is ambiguous; update the markdown near that heading (and the two
occurrences after TSDoc and JSDoc) to clarify what "Context7" means by either
adding a short parenthetical explanation (e.g., "(internal context identifier
for source mapping)" or similar) or by replacing it with a link to the internal
documentation that defines Context7 so external readers understand the
reference; ensure the change references the same heading "## 9) Sources Used For
This Skill" and the two lines that currently end with "(Context7)".
In @.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-module.md:
- Around line 10-13: The three sentences beginning with "Use" are repetitive;
update the module doc copy so the first line keeps "Use `@module` at file/module
scope for package organization and generated docs," but rephrase either "Use
this when: documenting JavaScript module entrypoints or grouped exports." or
"Use this when:" to vary the opening—for example change to "Apply it when
documenting JavaScript module entrypoints or grouped exports." and keep "Avoid
this when: annotating individual functions with module-level semantics." This
will reduce repetition while preserving meaning and the three referenced phrases
("Use `@module`...", "Use this when:", "Avoid this when:") for clarity.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-typedef-property.md:
- Around line 12-13: Update the guidance under the "Avoid this when:" line in
jsdoc-typedef-property.md to remove the contradictory phrasing and clarify
intent: replace the current "Avoid this when: duplicating long inline object
type expressions everywhere." with a clear alternative such as "Use this to
avoid: duplicating long inline object type expressions everywhere." or "Avoid
inline shapes when: the same structure appears in multiple places." — target the
exact "Avoid this when:" line and adjust the following sentence to one of these
suggested rewrites so the meaning aligns with the `@typedef` purpose.
In @.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-yields.md:
- Around line 15-22: The "Incorrect" example currently shows a generator with no
yielded values, so change the snippet for function* fibonacci() to include a
simple yield (e.g., add a line such as yield 0; inside function* fibonacci()) so
the example clearly demonstrates the missing `@yields` type while keeping the rest
of the snippet unchanged; update the code block in jsdoc-yields.md so the
incorrect example contains a visible yield statement for the fibonacci
generator.
In @.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-no-defaults.md:
- Around line 26-42: Add an example showing an optional param without a default
to clarify that `@param` {number} [foo] is allowed when the parameter is truly
optional; update the examples block by inserting a "Correct (optional param
without default value):" snippet that uses the same symbol names (e.g., `@param`
{number} [foo] and function quux(foo) {}) so readers see that the square-bracket
optional marker is acceptable as long as no default value is present in the
function signature (fix the suggested snippet which incorrectly used foo = 7).
In @.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-param.md:
- Around line 12-13: The "Avoid this when:" line is confusing because it
describes the incorrect pattern instead of scenarios where the rule does not
apply; update the wording under the "**Avoid this when:**" heading to clearly
state when the jsdoc-param rule is less applicable (for example: "Avoid this
when using TypeScript with explicit type annotations or when types are reliably
inferred from other annotations or tooling"), ensuring the guidance contrasts
with the "**Use this when:**" line and mentions TypeScript/type inference as
concrete exceptions.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-property-namepaths.md:
- Around line 13-14: Reword the "Avoid this when:" guidance so it states a clear
scenario where nested namepaths are unnecessary rather than describing the
incorrect pattern; update the sentence under the "Avoid this when:" heading (the
line that currently reads "only top-level object parameter is documented") to
something like "When you are only documenting a single top-level object
parameter and none of its nested properties need separate documentation" so it
indicates when the rule should not apply; keep the "Use this when:" sentence
as-is and ensure the revised line lives under the same heading in
jsdoc-property-namepaths.md.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param-type.md:
- Around line 12-13: Update the "Avoid this when:" line in
jsdoc-require-param-type.md to explain scenarios where explicit JSDoc type
expressions are unnecessary rather than showing the bad pattern; for example,
replace the current "Avoid this when: writing untyped `@param` tags like `@param
foo`." with a clear guidance such as "Avoid this when: your project already uses
a typed system (e.g., TypeScript or JSDoc typedefs) or when parameter types are
documented via inline TypeScript annotations or external type definitions, so
redundant `{type}` expressions are not needed." Ensure the change is made in the
header text near the rule title (jsdoc-require-param-type) so readers understand
when to skip explicit JSDoc type expressions.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param.md:
- Around line 12-13: Update the wording in the jsdoc-require-param rule's
guidance: replace the awkward sentence "Avoid this when: some parameters are
undocumented in the JSDoc block" (under the "Avoid this when:" section) with a
clearer context-based phrasing such as "Avoid this when: TypeScript types
already provide complete parameter documentation" so the rule describes when not
to apply instead of describing a violation state.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-description.md:
- Around line 12-13: Update the wording of the "Avoid this when:" sentence in
jsdoc-require-property-description (currently "Avoid this when: leaving property
tags without explanatory text") to match the clarity used in
jsdoc-require-param.md by describing the context where the rule should not apply
rather than the violation; replace it with something like "Avoid this when: the
property tag already includes an explanatory description" so the line refers to
a valid exemption context instead of restating the violation.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns.md:
- Around line 12-13: Update the guidance text under the "Avoid this when:"
heading in jsdoc-require-returns.md so it describes genuine exceptions where the
rule should not apply instead of listing violations; specifically replace the
current phrasing that reads "omitting `@returns` for returning functions or
adding duplicate `@returns` tags" with a clearer exception statement (for
example: when a function truly has no return value, or when return information
is inherited from external type declarations) while keeping the rule's intent
intact.
In
@.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-yields.md:
- Around line 35-44: Update the "Correct (single `@yields`)" example to use
proper JSDoc type braces: change the `@yields` tag in the `quux` generator
example from `@yields Foo` to `@yields {Foo}` so it matches the documented JSDoc
type syntax and the rest of the docs.
In @.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-throws.md:
- Line 15: Update the compound adjective "no throws contract" to a hyphenated
form "no-throws-contract" in the documentation string that currently appears as
"**Incorrect (no throws contract):**" (and any other occurrences of the same
phrase) so the compound modifier is clear and follows standard style; simply
replace the unhyphenated phrase with "no-throws-contract" in the JSDoc guidance
text.
In @.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-example.md:
- Around line 10-13: The three lines repeat "Use" awkwardly; reword them to
avoid repetition by changing "Use `@example` for tricky, non-obvious, or
high-value usage patterns." to remain as the short lead, and replace "**Use this
when:**" with "When to use:" and "**Avoid this when:**" with "When to avoid:" so
the header verbs aren't duplicated while preserving intent and emphasis for the
example guidance.
In @.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-param.md:
- Line 57: Update the heading that reads "**Preferred (VS Code
hover/autocomplete friendly pattern):**" to hyphenate the compound adjective so
it becomes "**Preferred (VS Code hover/autocomplete-friendly pattern):**" to
correct the grammar; locate the exact string "autocomplete friendly" in the file
and replace it with "autocomplete-friendly".
In @.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-throws.md:
- Line 15: Update the wording in the tsdoc example header by replacing the
compound adjective "no throw contract" with the hyphenated form
"no-throw-contract" so the phrase reads "**Incorrect (no-throw-contract):**";
locate the header text in tsdoc-throws.md and apply the hyphenation consistently
wherever the compound adjective appears.
In `@docs/configuration.mdx`:
- Around line 59-64: Update the schema paths in the "Schemas" section so they
use the absolute unpkg URLs instead of root-relative paths: replace
`/schemas/readie.schema.json` with
`https://unpkg.com/readie/schemas/readie.schema.json` and
`/schemas/readie.global.schema.json` with
`https://unpkg.com/readie/schemas/readie.global.schema.json` so the Project
schema and Global schema entries match the examples in starter-config.ts and
docs/quickstart.mdx.
In `@docs/introduction.mdx`:
- Around line 21-24: Condense and reword the numbered list to reduce repetition
of the word “Readie”: keep step 1 as “Create a readie.json config in your
project,” then change steps 2–4 to concise, varied verbs (e.g., “Validate and
load the config,” “Render markdown from the configured sections,” “Write
README.md (or a custom output path) when content changes”) so the flow is
smoother and you avoid repeating “Readie …” three times in a row.
In `@docs/workspace.mdx`:
- Around line 7-40: Add documentation for the CLI's --no-global flag in the
workspace guide next to the generate:workspace examples: describe that
--no-global disables global config discovery and merging, and show the usage
alongside the existing examples for --config-name and --root; reference the
generate:workspace command and the --no-global flag so readers can find the
option easily.
In `@src/readme-generator/generator.ts`:
- Around line 99-104: Update the JSDoc for the function that "Generates a README
for a single project config" by removing the type braces from the `@param` and
`@returns` tags: replace the "@param {GenerateSingleOptions} options - ..." tag
with a plain "@param options - Generation options for one config file" and
replace the "@returns {Promise<GenerateSingleResult>} Generation metadata..."
tag with a plain "@returns Generation metadata including output path and whether
content changed" so types are no longer wrapped in braces; this JSDoc sits
alongside the GenerateSingleOptions/GenerateSingleResult usage in generator.ts.
- Around line 229-235: The JSDoc for the workspace README generator uses type
braces which should be removed—update the comment for the function (the block
describing "Generates README files for projects inside a workspace root") so the
`@param` and `@returns` lines reference the types by name without surrounding braces
(remove {GenerateWorkspaceOptions} and {Promise<GenerateWorkspaceResult>}), and
leave the descriptive text intact; target the JSDoc associated with the
generateWorkspace function (and any occurrences of GenerateWorkspaceOptions /
GenerateWorkspaceResult in that comment) and adjust the tags accordingly.
- Around line 18-23: Update the TSDoc block for the function that "Normalizes
repeated and comma-separated `--package` option values." by removing JSDoc-style
type braces from the `@param` and `@returns` tags (e.g., change "@param {string[]}
values" to "@param values" and "@returns {Set<string>}" to "@returns
Set<string>" or simply "@returns" per your style guide), leaving the actual
TypeScript types on the function signature intact; ensure the param name
"values" and the descriptive text remain unchanged so the doc is
TSDoc-compliant.
- Around line 55-59: The TSDoc `@returns` line currently uses JSDoc-style type
braces; remove the braces so the return type is written in TSDoc style — replace
"@returns {Promise<string | undefined>} The package name when present, otherwise
`undefined`." with "@returns Promise<string | undefined> The package name when
present, otherwise `undefined`." in the docblock for the function that "Attempts
to read a package name from `package.json`" in generator.ts.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-module.md
Show resolved
Hide resolved
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-typedef-property.md
Outdated
Show resolved
Hide resolved
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-yields.md
Show resolved
Hide resolved
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-no-defaults.md
Show resolved
Hide resolved
| /** | ||
| * Normalizes repeated and comma-separated `--package` option values. | ||
| * | ||
| * @param {string[]} values - Raw CLI values that may contain comma-delimited package names. | ||
| * @returns {Set<string>} A de-duplicated set of trimmed package names. | ||
| */ |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Remove JSDoc type braces from TSDoc comments.
This TypeScript file uses JSDoc-style {type} annotations in the @param and @returns tags (e.g., @param {string[]} values). Per the TSDoc reference introduced in this same PR (line 102 of reference.md), this is explicitly listed as a mistake to avoid: "Using JSDoc type braces in TSDoc @param lines."
In TypeScript, types are inferred from the signature—omit the braces for TSDoc compliance.
Proposed fix
/**
* Normalizes repeated and comma-separated `--package` option values.
*
- * `@param` {string[]} values - Raw CLI values that may contain comma-delimited package names.
- * `@returns` {Set<string>} A de-duplicated set of trimmed package names.
+ * `@param` values - Raw CLI values that may contain comma-delimited package names.
+ * `@returns` A de-duplicated set of trimmed package names.
*/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Normalizes repeated and comma-separated `--package` option values. | |
| * | |
| * @param {string[]} values - Raw CLI values that may contain comma-delimited package names. | |
| * @returns {Set<string>} A de-duplicated set of trimmed package names. | |
| */ | |
| /** | |
| * Normalizes repeated and comma-separated `--package` option values. | |
| * | |
| * `@param` values - Raw CLI values that may contain comma-delimited package names. | |
| * `@returns` A de-duplicated set of trimmed package names. | |
| */ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/readme-generator/generator.ts` around lines 18 - 23, Update the TSDoc
block for the function that "Normalizes repeated and comma-separated `--package`
option values." by removing JSDoc-style type braces from the `@param` and `@returns`
tags (e.g., change "@param {string[]} values" to "@param values" and "@returns
{Set<string>}" to "@returns Set<string>" or simply "@returns" per your style
guide), leaving the actual TypeScript types on the function signature intact;
ensure the param name "values" and the descriptive text remain unchanged so the
doc is TSDoc-compliant.
| /** | ||
| * Attempts to read a package name from `package.json` beside the config file. | ||
| * | ||
| * @returns {Promise<string | undefined>} The package name when present, otherwise `undefined`. | ||
| */ |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Same JSDoc type braces issue in TSDoc.
/**
* Attempts to read a package name from `package.json` beside the config file.
*
- * `@returns` {Promise<string | undefined>} The package name when present, otherwise `undefined`.
+ * `@returns` The package name when present, otherwise `undefined`.
*/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Attempts to read a package name from `package.json` beside the config file. | |
| * | |
| * @returns {Promise<string | undefined>} The package name when present, otherwise `undefined`. | |
| */ | |
| /** | |
| * Attempts to read a package name from `package.json` beside the config file. | |
| * | |
| * `@returns` The package name when present, otherwise `undefined`. | |
| */ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/readme-generator/generator.ts` around lines 55 - 59, The TSDoc `@returns`
line currently uses JSDoc-style type braces; remove the braces so the return
type is written in TSDoc style — replace "@returns {Promise<string | undefined>}
The package name when present, otherwise `undefined`." with "@returns
Promise<string | undefined> The package name when present, otherwise
`undefined`." in the docblock for the function that "Attempts to read a package
name from `package.json`" in generator.ts.
| /** | ||
| * Generates a README for a single project config. | ||
| * | ||
| * @param {GenerateSingleOptions} options - Generation options for one config file. | ||
| * @returns {Promise<GenerateSingleResult>} Generation metadata including output path and whether content changed. | ||
| */ |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Remove type braces from @param and @returns.
/**
* Generates a README for a single project config.
*
- * `@param` {GenerateSingleOptions} options - Generation options for one config file.
- * `@returns` {Promise<GenerateSingleResult>} Generation metadata including output path and whether content changed.
+ * `@param` options - Generation options for one config file.
+ * `@returns` Generation metadata including output path and whether content changed.
*/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Generates a README for a single project config. | |
| * | |
| * @param {GenerateSingleOptions} options - Generation options for one config file. | |
| * @returns {Promise<GenerateSingleResult>} Generation metadata including output path and whether content changed. | |
| */ | |
| /** | |
| * Generates a README for a single project config. | |
| * | |
| * `@param` options - Generation options for one config file. | |
| * `@returns` Generation metadata including output path and whether content changed. | |
| */ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/readme-generator/generator.ts` around lines 99 - 104, Update the JSDoc
for the function that "Generates a README for a single project config" by
removing the type braces from the `@param` and `@returns` tags: replace the "@param
{GenerateSingleOptions} options - ..." tag with a plain "@param options -
Generation options for one config file" and replace the "@returns
{Promise<GenerateSingleResult>} Generation metadata..." tag with a plain
"@returns Generation metadata including output path and whether content changed"
so types are no longer wrapped in braces; this JSDoc sits alongside the
GenerateSingleOptions/GenerateSingleResult usage in generator.ts.
| /** | ||
| * Generates README files for projects inside a workspace root. | ||
| * | ||
| * @param {GenerateWorkspaceOptions} options - Workspace generation options. | ||
| * @returns {Promise<GenerateWorkspaceResult>} Aggregated status across updated, unchanged, skipped, and failed projects. | ||
| * @throws Error if the workspace root does not exist. | ||
| */ |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Remove type braces from workspace generation JSDoc.
/**
* Generates README files for projects inside a workspace root.
*
- * `@param` {GenerateWorkspaceOptions} options - Workspace generation options.
- * `@returns` {Promise<GenerateWorkspaceResult>} Aggregated status across updated, unchanged, skipped, and failed projects.
+ * `@param` options - Workspace generation options.
+ * `@returns` Aggregated status across updated, unchanged, skipped, and failed projects.
* `@throws` Error if the workspace root does not exist.
*/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Generates README files for projects inside a workspace root. | |
| * | |
| * @param {GenerateWorkspaceOptions} options - Workspace generation options. | |
| * @returns {Promise<GenerateWorkspaceResult>} Aggregated status across updated, unchanged, skipped, and failed projects. | |
| * @throws Error if the workspace root does not exist. | |
| */ | |
| /** | |
| * Generates README files for projects inside a workspace root. | |
| * | |
| * `@param` options - Workspace generation options. | |
| * `@returns` Aggregated status across updated, unchanged, skipped, and failed projects. | |
| * `@throws` Error if the workspace root does not exist. | |
| */ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/readme-generator/generator.ts` around lines 229 - 235, The JSDoc for the
workspace README generator uses type braces which should be removed—update the
comment for the function (the block describing "Generates README files for
projects inside a workspace root") so the `@param` and `@returns` lines reference
the types by name without surrounding braces (remove {GenerateWorkspaceOptions}
and {Promise<GenerateWorkspaceResult>}), and leave the descriptive text intact;
target the JSDoc associated with the generateWorkspace function (and any
occurrences of GenerateWorkspaceOptions / GenerateWorkspaceResult in that
comment) and adjust the tags accordingly.
…rules - Updated various documentation files to improve phrasing and clarity, including changes to usage guidance and avoidance recommendations. - Added explicit examples and corrected formatting for better readability. - Ensured consistency in parameter and return type documentation across multiple files. - Revised schema references in configuration documentation for accuracy.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (19)
.agents/skills/tsdoc-jsdoc-authoring/reference.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-module.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-typedef-property.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-yields.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-no-defaults.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-param.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-property-namepaths.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param-type.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-description.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-yields.md.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-throws.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-example.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-param.md.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-throws.mddocs/configuration.mdxdocs/introduction.mdxdocs/workspace.mdx
🧰 Additional context used
🪛 LanguageTool
.agents/skills/tsdoc-jsdoc-authoring/reference.md
[uncategorized] ~194-~194: The official name of this software platform is spelled with a capital “H”.
Context: ...identifier for source mapping) - JSDoc: /jsdoc/jsdoc.github.io (Context7 internal context identifi...
(GITHUB)
🔇 Additional comments (20)
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-property-namepaths.md (1)
10-15: Clear guidance and scope.
The “Use this when / Avoid this when” framing is precise and actionable..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-no-defaults.md (1)
1-55: Docs content looks consistent and clear.
Examples correctly distinguish default-in-tag vs optional without default, and guidance matches rule intent..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-param.md (1)
1-33: Clear guidance and examples.
Use/avoid conditions and typed param example align well with the rule’s intent..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param-type.md (1)
1-29: Looks good.
Examples and applicability guidance correctly support the rule..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-param.md (1)
1-40: Solid documentation and configuration detail.
Rule guidance and examples are consistent and actionable..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-returns.md (1)
1-53: Clear rule intent and examples.
Exceptions and configuration options are well stated..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-throws.md (1)
1-32: LGTM! Well-structured JSDoc guidance.The documentation clearly explains when and how to use the
@throwstag for error contracts. The front matter appropriately marks this as HIGH impact, the guidance distinguishes expected from incidental errors, and the examples effectively contrast missing vs. complete throws documentation. The past review comment regarding hyphenation has already been addressed..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-throws.md (1)
1-32: LGTM! Clear and well-structured documentation.The documentation clearly explains when and how to use the
@throwstag, with good examples distinguishing contract-relevant failures from incidental errors. The past hyphenation issue has been addressed..agents/skills/tsdoc-jsdoc-authoring/reference.md (2)
194-194: Static analysis false positive can be safely ignored.The LanguageTool hint suggesting "GitHub" with a capital "H" is a false positive. The text
/jsdoc/jsdoc.github.iois a technical path/URL reference, not prose about the GitHub company, so the lowercase form is correct for the domain suffix.
1-194: LGTM! Comprehensive and well-organized reference.The document provides thorough TSDoc/JSDoc guidance with clear structure, practical examples, and helpful templates. The Context7 clarification from the past review has been properly addressed, making the sources section clear for readers.
.agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-param.md (1)
1-71: LGTM! Excellent progression from incorrect to preferred patterns.The documentation effectively demonstrates parameter documentation best practices, with a particularly strong "preferred" pattern showing how named types improve IDE hover/autocomplete support. The past hyphenation issue has been addressed.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-module.md (1)
1-32: Clear guidance and well-contrasted examples.This cleanly explains when to apply
@moduleand includes helpful correct/incorrect snippets..agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-property-description.md (1)
1-33: Concise rule statement with solid examples.The guidance is straightforward and the examples illustrate the requirement clearly.
docs/introduction.mdx (1)
1-33: Well-structured intro and workflow overview.The sequence is easy to follow and the config source explanation is crisp.
docs/workspace.mdx (1)
1-55: Comprehensive workspace guide and CLI coverage.The command examples and option explanations are complete and practical.
docs/configuration.mdx (1)
1-64: Solid configuration reference with helpful schema guidance.The field table, merge behavior, placeholders, and schema references are clearly documented.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/core/jsdoc-require-yields.md (1)
1-50: LGTM! Comprehensive and well-structured documentation.The file provides clear guidance on the
@yieldsrequirement for generators with:
- Appropriate "HIGH" impact rating for contract documentation
- Multiple incorrect examples demonstrating common errors
- Correct example using proper JSDoc type syntax (
@yields {Foo})- Well-documented configuration options with defaults
The past review comment regarding type braces has been addressed (line 39 correctly uses
{Foo})..agents/skills/tsdoc-jsdoc-authoring/rules/tsdoc/core/tsdoc-example.md (3)
10-13: Repetition issue from previous review has been addressed.The headers have been successfully updated from "Use this when" and "Avoid this when" to "When to use" and "When to avoid", which resolves the awkward repetition flagged in the previous review. The current wording is clear and concise.
As an optional refinement, you could capitalize the fragments following the colons for consistency:
- "When to use: Behavior is subtle..."
- "When to avoid: Examples are trivial..."
However, the current lowercase style is also acceptable for bullet-style items.
15-22: Clear illustration of missing documentation.The "incorrect" example effectively demonstrates the problem: a complex retry function without usage guidance. The contrast with the corrected version makes the value of
@exampleimmediately clear.
24-35: Excellent example of proper@exampleusage.The corrected version demonstrates best practices:
- Inline
@exampleblock within the JSDoc comment- Realistic usage showing async/await pattern
- Clarifies how to invoke the function with a callback
- Proper markdown nesting (4 outer, 3 inner backticks)
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-yields.md:
- Around line 26-33: The examples for the `fibonacci` generator are
inconsistent: the "Incorrect" example uses `yield 0;` but the "Correct (explicit
yielded contract)" example's `function* fibonacci() {}` has no body; update the
correct example by adding the same `yield 0;` inside `function* fibonacci()` so
both examples show the same generator behavior while demonstrating the proper
`@yields {number}` JSDoc usage.
.agents/skills/tsdoc-jsdoc-authoring/rules/jsdoc/advanced/jsdoc-yields.md
Outdated
Show resolved
Hide resolved
1 participant
No description provided.